API Docs for: 1.0.0
Show:

TYRO Module

Overview

The Tyro iClient provides a javascript client side library to initiate payment transactions with a Tyro terminal. There are two ways to use it.

Within this split you can choose to have receipts printed by the terminal or returned as pre-formatted blocks of text to be printed by a printer attached to the POS.

Sequence Diagrams

The following diagrams show the interaction between the POS and iClient in increasing order of control taken by the POS:
  1. IClient with UI - terminal prints receipt
  2. IClient with UI - POS prints receipt
  3. IClient (POS UI) - terminal prints receipt
  4. IClient (POS UI) - POS prints receipt

Transaction callbacks

The main coding task for a POS using the Tyro iClient is implementing the set of transaction callbacks. The full set only applies to a POS taking control over the user interface (using the TYRO.IClient). Each of the initiate purchase, refund and open tab methods involve the following set of callbacks:
Question Callback (TYRO.IClient only)
Invoked when the terminal requires the merchant to answer a question in order to proceed with the transaction. Called with the following parameters:
  • questionObject
    The question to be presented to the merchant consisting of:
    • textString
      The message to present to the merchant.
    • optionsArray[String]
      The set of button labels to present. A button should be presented to the merchant for each element in this array.
  • answerCallbackFunction
    The callback to be used to provide the merchant's answer to the question. The POS should call this function when the merchant clicks one of the buttons passing the label of the clicked button (from the options array in the question).

Status Message Callback (TYRO.IClient only)
Invoked to advertise what is happening on terminal, which is typically facing the customer rather than the merchant. Called with a single String argument. For example "Select account".

Receipt Callback
Invoked when integrated receipts are enabled and a merchant copy of the receipt is available. Ignored if integrated receipt printing is disabled. Called with the following parameters:
  • receiptObject
    A merchant copy of the receipt consisting of:
    • signatureRequiredBoolean
      Indicates whether a signature line should be printed and a customer signature collected.
    • merchantReceiptString
      Text representation of the Tyro receipt intended for the merchant. Formatted to be printed in a monospaced font.

Transaction Complete Callback
Invoked when the transaction has been completed on the terminal. Called with a subset of the following parameters:

  • transactionDataObject
    An object consisting of:
    • resultString
      One of the following values: APPROVED, CANCELLED, REVERSED, DECLINED, SYSTEM ERROR, NOT STARTED, UNKNOWN.
      The merchant will only receive money if this value is APPROVED.
      UNKNOWN means the merchant should look at the terminal to determine what happened. Typically this would indicate a network error.
    • cardTypeString
      The scheme displayed on the card (Visa, Mastercard, etc).
    • transactionReferenceString
      Also known as a STAN, this is Tyro's reference to this transaction. Quote this to Tyro Customer Support if you run into any issues with a transaction.
    • authorisationCodeString
      The Scheme's reference to the transaction. Quote this number to Visa/Mastercard/etc if the issue is on their end.
    • issuerActionCodeString
      The raw result code returned by the card issuer.
    • elidedPanString
      The (elided) credit card number used for this transaction.
    • rrnString
      The Retrieval Reference Number is a unique number generated by the Payment Service for a specific merchant. Guaranteed to be unique for a 7-day period.
    • tipAmountString
      If you are performing a Tip Completion, the tip component will be returned here, in cents.
    • tipCompletionReferenceString
      Tyro's reference to the Tip Completion.
    • tabCompletionReferenceString
      Tyro's reference to a Tab Completion.
    • preAuthCompletionReferenceString
      Tyro's reference to a PreAuth Completion.
    • cardTokenString
      If you are requesting a Card Token, the Card Token will be returned here, in 30 case insensitive alphanumeric characters.
    • cardTokenExpiryDateString
      If you are requesting a Card Token, the expiry of the Card Token will be returned here, in yyyy-MM-dd format.
    • cardTokenStatusCodeString
      If you are requesting a Card Token, the status code of the Card Token request will be returned here, 00 indicates success.
    • cardTokenErrorMessageString
      If you are requesting a Card Token and Tyro fails to generate one for you, the reason for the failure will be returned here.
    • customerReceiptString
      Text representation of the Tyro receipt intended for the customer. Only included if integrated receipt printing is enabled. Formatted to be printed in a monospaced font.

      • For Healthpoint Claims

    • healthpointRefTagString
      The reference tag generated by the terminal that identifies a transaction per terminal
    • healthpointTotalBenefitAmountString
      Total benefit amount for all claim items
    • healthpointSettlementDateTimeString
      Settlement date time as decided by the iCS system/health fund
    • healthpointTerminalDateTimeString
      The transaction date time of the claim/s
    • healthpointMemberNumberString
      Private health fund member number of cardholder
    • healthpointProviderId"String
      Provider ID matching the original request
    • healthpointServiceTypeString
      Service type matching the original request
    • healthpointGapAmountString
      The gap amount. Will only be present on successful claims and voids.
    • healthpointPhfResponseCodeString
      The response code from the private health fund.
    • healthpointPhfResponseCodeDescriptionString
      The description of the response code from the private health fund.
    • healthpointHealthFundNameString
      The name of the private health fund.
    • healthpointHealthFundIdentifyingDigitsString
      The identifying digits of the private health fund.
    • healthpointClaimItemsObject
      • claimAmountString
        Claim Item amount in cents (max. 10 digits)
      • rebateAmountString
        Rebate amount for the claim made (max. 10 digits)
      • serviceCodeString
        Item Service Code
      • descriptionString
        Item description (max. 32 characters)
      • serviceReferenceString
        Item Service Ref (max. 3 characters)
      • patientIdString
        Patient id as on card (2 digits)
      • serviceDateString
        Date of claim in format "yyyyMMddhhmmss"
      • responseCodeString
        Individual response code for this item

This module provides the following classes: